<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Using Interceptors - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level3"><a href="gjsdf.html">Using Alternatives</a></p>
<p class="toc level4"><a href="gjsdf.html#gkhpo">Using Specialization</a></p>
<p class="toc level3 tocsp"><a href="gkgkv.html">Using Producer Methods and Fields</a></p>
<p class="toc level3"><a href="gkhic.html">Using Events</a></p>
<p class="toc level4"><a href="gkhic.html#gkhhy">Defining Events</a></p>
<p class="toc level4"><a href="gkhic.html#gkhnf">Using Observer Methods to Handle Events</a></p>
<p class="toc level4"><a href="gkhic.html#gkhih">Firing Events</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Using Interceptors</a></p>
</div>
<p class="toc level3"><a href="gkhqf.html">Using Decorators</a></p>
<p class="toc level3"><a href="gkhqc.html">Using Stereotypes</a></p>
<p class="toc level2 tocsp"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gkhic.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gkhqf.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gkhjx"></a><h2>Using Interceptors</h2>
<a name="indexterm-1575"></a><a name="indexterm-1576"></a><p>An <b>interceptor</b> is a class that is used to interpose in method invocations
or lifecycle events that occur in an associated target class. The interceptor performs
tasks, such as logging or auditing, that are separate from the business logic
of the application and that are repeated often within an application. Such tasks
are often called <b>cross-cutting</b> tasks. Interceptors allow you to specify the code
for these tasks in one place for easy maintenance. When interceptors were first
introduced to the Java EE platform, they were specific to enterprise beans. You
can now use them with Java EE managed objects of all kinds, including
managed beans.</p>

<p>For information on Java EE interceptors, see <a href="gkeed.html">Chapter&nbsp;48, Using Java EE Interceptors</a>.</p>

<p>An interceptor class often contains a method annotated <tt>@AroundInvoke</tt>, which specifies the
tasks the interceptor will perform when intercepted methods are invoked. It can also
contain a method annotated <tt>@PostConstruct</tt>, <tt>@PreDestroy</tt>, <tt>@PrePassivate</tt>, or <tt>@PostActivate</tt>, to specify lifecycle callback
interceptors, and a method annotated <tt>@AroundTimeout</tt>, to specify EJB timeout interceptors. An interceptor class
can contain more than one interceptor method, but it must have no more
than one method of each type.</p>

<p>Along with an interceptor, an application defines one or more <b>interceptor binding types</b>, which
are annotations that associate an interceptor with target beans or methods. For example,
the <tt>billpayment</tt> example contains an interceptor binding type named <tt>@Logged</tt> and an interceptor named
<tt>LoggedInterceptor</tt>. The interceptor binding type declaration looks something like a qualifier declaration, but it
is annotated with <tt>javax.interceptor.InterceptorBinding</tt>:</p>

<pre>@Inherited
@InterceptorBinding
@Retention(RUNTIME)
@Target({METHOD, TYPE})
public @interface Logged {
}</pre><p>An interceptor binding also has the <tt>java.lang.annotation.Inherited</tt> annotation, to specify that the
annotation can be inherited from superclasses. The <tt>@Inherited</tt> annotation also applies to custom scopes
(not discussed in this tutorial), but does not apply to qualifiers.</p>

<p>An interceptor binding type may declare other interceptor bindings.</p>

<p>The interceptor class is annotated with the interceptor binding as well as with
the <tt>@Interceptor</tt> annotation. For an example, see <a href="gkhpa.html#gkhrq">The <tt>LoggedInterceptor</tt> Interceptor Class</a>.</p>

<p>Every <tt>@AroundInvoke</tt> method takes a <tt>javax.interceptor.InvocationContext</tt> argument, returns a <tt>java.lang.Object</tt>, and throws an
<tt>Exception</tt>. It can call <tt>InvocationContext</tt> methods. The <tt>@AroundInvoke</tt> method must call the <tt>proceed</tt>
method, which causes the target class method to be invoked.</p>

<p>Once an interceptor and binding type are defined, you can annotate beans and
individual methods with the binding type to specify that the interceptor is to
be invoked either on all methods of the bean or on specific
methods. For example, in the <tt>billpayment</tt> example, the <tt>PaymentHandler</tt> bean is annotated <tt>@Logged</tt>,
which means that any invocation of its business methods will cause the interceptor's
<tt>@AroundInvoke</tt> method to be invoked:</p>

<pre>@Logged
@SessionScoped
public class PaymentHandler implements Serializable {...}</pre><p>However, in the <tt>PaymentBean</tt> bean, only the <tt>pay</tt> and <tt>reset</tt> methods have
the <tt>@Logged</tt> annotation, so the interceptor is invoked only when these methods are
invoked:</p>

<pre>@Logged
public String pay() {...}

@Logged
public void reset() {...}</pre><p>In order for an interceptor to be invoked in a CDI application,
it must, like an alternative, be specified in the <tt>beans.xml</tt> file. For example, the
<tt>LoggedInterceptor</tt> class is specified as follows:</p>

<pre>&lt;interceptors>
    &lt;class>billpayment.interceptors.LoggedInterceptor&lt;/class>
&lt;/interceptors></pre><p>If an application uses more than one interceptor, the interceptors are invoked in
the order specified in the <tt>beans.xml</tt> file.</p>


         </div>
         <div class="navigation">
             <a href="gkhic.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gkhqf.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

